Ensuring Compatibility with Next Generation Amiga Graphics Hardware Copyright (c) 1991-1992 Commodore International Services Corporation All Rights Reserved. CONFIDENTIAL AND PRELIMINARY NOTE - This document contains a great deal of information to help you remain compatible with and take advantage of V39 and future chips. Please also consult all current readmes and release notes for the latest information on current implementations and features. Do NOT distribute this information. This information may only be discussed in Commodore's closed developer conferences, and only if Commodore opens a topic for discussion. CONFIDENTIAL - The information contained herein is confidential and proprietary. This information is provided under non-disclosure for inhouse use only by registered Amiga developers. PRELIMINARY - The information contained herein is preliminary. WARNING - The information contained herein is subject to change without notice. Commodore specifically does not make any endorsement or representation with respect to use, results, or performance of the information (including without limitations its capabilities, appropriateness, reliability, currentness, or availability). DISCLAIMER - This information is provided "as is" without warranty of any kind, either express or implied. The entire risk as to the use of this information is assumed by the user. In no event will Commodore or its affiliated companies be liable for any damages, direct, incidental, special or consequential, resulting from any defect in the information, even if advised of the possibilities of such damages. Table of Contents Introduction/Purpose New Hardware Features Ensuring Compatibility Known No-Nos Taking Advantage of New Features What to Expect From New Software Table: New Modes Introduction/Purpose The capabilities of the built-in Amiga graphics hardware had not changed significantly between the introduction of the Amiga 1000 in 1985 and the release of the Amiga 3000 in 1990. The ECS chipset and the display enhancer added several new graphics modes and increased the functionality of existing modes -- yet the market demands more. Commodore is working on a graphics chipset which will include many substantial new features. This document explains the features of this next generation Amiga graphics hardware, and ways to ensure application compatibility with these features. Additionally, coding methods are outlined which will allow current software to automatically exploit some of the new features. Finally, so that developers can begin "sketching out" applications that will support the new chipset, a brief overview of some of the relevant planned system software changes is provided. New Hardware Features This is a summary of the new Amiga graphics hardware's features. Enhanced Bandwidth - A 32 bit wide data bus allows doubling of memory bandwidth (to 2x the normal bandwidth) and supports the input of 32 bit wide bitplane and sprite data. Bandwidth may be doubled again (to 4x) by using Fast Page Mode RAM. More Bitplanes - The maximum number of bitplanes has increased to 8 in all resolution modes. This translates to a 256 entry color table for each available mode. Enhanced Dual Playfield Support - Each playfield may now have up to 4 bitplanes. The bank of 16 colors in the 256 color table is independently selectable for each playfield. Larger Palette - Each entry in the color table may now be 25 bits wide (8 bits each for Red, Blue, and Green data -- plus 1 bit for genlock information). This translates to a palette of 16,777,216 colors. Enhanced Sprite Support - Sprite resolution can be set to lores, hires, or super-hires, independent of screen resolution. Attached sprites are now available in all modes. However, some new higher bandwidth modes may only allow one sprite. Odd and even sprites may use their own independent 16 color bank from the 256 color table. Old format sprites may still be 16 bits wide, and new format sprites may be 32 or 64 bits wide. Sprites may now optionally appear in the border region. The horizontal positioning resolution of sprites has increased to 35ns (equivalent to super-hires pixel widths.) Enhanced hardware scrolling support - Two extra bits allow seamless scrolling of up to 64 bit wide bitplanes in all resolutions. The resolution of bitplane scrolling has been increased to 35ns. Hardware scan doubling support - 15khz bitplanes and sprites may now be scan doubled for flicker free display on 31khz monitors, and for enhanced display sharing with 31khz bitplanes. ECS compatibility - New chips will power-up in an ECS compatibility mode, which will allow many older self-booting programs to be run on new machines. Ensuring Compatibility This section covers programming techniques which will help ensure that an application will work as expected when running on systems that use next generation graphics hardware. The most important thing to remember about maintaining compatibility (and this applies to all software-hardware issues) is to never access the hardware directly. As a few developers learned when users tried to run their applications on the Amiga 3000, hardware does change, and the correct way to access it is through the system software. When the hardware is changed, the system software changes with it, and old programs that use the new software have a better chance of running properly. An important issue here is that you should use the current system software. Applications should be written to run under release 2.0 of the operating system, as it will be the basis for all new hardware support, and release 1.3 cannot open the new modes. One of the main reasons that 2.0 will be a minimum requirement is the Display Database. Starting with the ECS chipset, not all machines have all display modes. This will be even more true in the future. The only way to know if a particular mode is available is to check the Display Database. For a detailed explanation of how to properly open a screen using the Display Database information to check for available modes, see the AmigaMail Volume Two articles entitled "An Introduction to V36 Screens and Windows" (page IV-3) and "Opening Screens and Windows on Any Amiga" (Page IV-17). Some of the pertinent details can also be found in the Paris DevCon notes article entitled "Monitors, Modes, and the Display Database." Once a screen has been opened, manipulating that screen should also be handled using system calls. In particular, these manipulations must be handled by the system software: allocation of graphics resources - Use graphics.library palette manipulation - Use graphics.library sprite manipulation - Use graphics.library manipulating icons - use icon.library allocating & changing colormaps & colortables - use graphics.library bitplane allocations - use AllocRaster(), but please refer to the next section for important information about limitations of AllocRaster() which will require a new and different function to be called. Furthermore, these manipulations should be handled by the system software whenever possible: drawing operations - Use graphics.library and intuition.library blitter operations - Use Blt[BitMap, RastPort, etc.] functions & macros (from graphics.library.) REMEMBER -- When using the blitter directly, ALWAYS use the system's WaitBlit() function instead of your own. The system knows about and handles problems with the BLITTER_DONE signal that different revisions of the Agnus chip have. Remember that the internals of system structures are subject to change or extension. For new graphics hardware, structures likely to be extended those associated with ColorMaps, ViewPortExtras, Sprites, and many others. To deal with the "shifting sands" of system structures, developers should use system calls to allocate, create, and manipulate these structures. For example, pre-V39 applications should always use InitBitMap to properly initialize a BitMap structure. Applications that support V39 should use the new AllocBitMap() call to handle both allocation and initialization. Even structures that may not change should still be accessed with system calls, because their contents may be calculated in different ways. If an allocation call is available, use it. If an initialization call is available, use it. See the V39 graphics.doc autodoc for specifications of new functions such as AllocBitMap(). Not all system structures have "Get" and "Set" calls, but developers need to use the ones that do exist. For example, it is better to use "SetAPen(myRastPort,n)" instead of "myRastPort->FgPen=n; SetDrMd()". Many additional Set and Get functions are provided in V39. For upwards compatibility, use always the Set and Get functions when available. A note about hardware -- the new chips will power-up in an ECS compatible state, which will allow a large portion of older, self-booting (read - "games") software to run even though the hardware is hit hard by such code. However, any software which is expects to be run after the operating system has been started will need to be very careful with the hardware. Once again: IF SOFTWARE DEPENDS ON HARDWARE AND THE HARDWARE CHANGES, THEN THE SOFTWARE WILL LIKELY BREAK. It is much better for the software to depend on the system software, which will be made to work with the new hardware. While some efforts are made to allow older hardware-banging code to function with new hardware, not everything can or will be compatible. You have been warned. With this in mind, for those developers who (for whatever reason) absolutely insist on using hardware directly, remember these points. (Paraphrased from the Amiga Hardware Reference Manual) Applications must not write spurious data to, or interpret data from, currently unused bits or addresses. Applications must set undefined bits to zero for writes and ignore them for reads. Play it safe -- when reading, mask out ALL the bits EXCEPT the ones you're actually interested in. Known No-Nos This short list represents some known coding strategies that will cause software to function incorrectly on new hardware. * Incorrect allocation of BitMap planes: This problem surfaces because the new chips have an increased fetch bandwidth. Bitplane data must be properly aligned in CHIP memory for this feature to work. Wrong - for(planenum=0; planenumBytesPerRow: Applications that use the supplied system functions to initialize and allocate BitMaps and their elements should be aware that the value of BitMap->BytesPerRow may be different from the expected value, depending on the bandwidth mode chosen, and the asked-for width of the allocated planes. We should explain why, a bit. First, due to fetch-alignment restrictions, we may need a higher granularity (BytesPerRow a multiple of 4 or 8, instead of just 2 under ECS). Second, BytesPerRow actually means two different things, which have always been identical, but aren't any more when using interleaved bitmaps. BytesPerRow officially means "the number of bytes you have to add to a pointer to a byte of the BitMap to get to the same place one row down". It no longer can be depended on to mean "the number of bytes in this row". For interleaved bitmaps, BytesPerRow is quite a bit larger than the number of bytes in this row. GetBitMapAttr( bm, BMA_WIDTH ) can return the true width in pixels. * Improper checking for PAL vs. NTSC: Software which uses release 2.0 (V36) or greater of the OS should NEVER use GfxBase->DisplayFlags to determine whether the machine is running in PAL or NTSC. GfxBase->DisplayFlags is obsolete and may not accurately reflect the desired mode of the user. WRONG- BOOL IsPAL; IsPAL=(GfxBase->DisplayFlags & PAL) ? TRUE : FALSE; Instead, the modeID of the default public screen (or the default monitor, if the default public screen is set to something other than PAL or NTSC (like VGA)) should be checked. Correct- Bool IsPAL; struct Screen *screen; ULONG modeID = LORES_KEY; struct DisplayInfo displayinfo; if (screen = LockPubScreen(NULL)) { if ((modeID = GetVPModeID(&(screen->ViewPort))) != INVALID_ID) { if (!((modeID & MONITOR_ID_MASK) == NTSC_MONITOR_ID || (modeID & MONITOR_ID_MASK) == PAL_MONITOR_ID)) modeID = LORES_KEY; } UnlockPubScreen(NULL,screen); } if (GetDisplayInfoData(NULL, (UBYTE *) &displayinfo,sizeof(struct DisplayInfo),DTAG_DISP,modeID)) { if (displayinfo.PropertyFlags & DIPF_IS_PAL) IsPAL = TRUE; else IsPAL = FALSE; } 39.82 NOTE: If the display mode of the default public screen is double-PAL, DIPF_IS_PAL is not yet set. This will be fixed. Note that if the display mode of the default public screen is "default", and the machine is PAL, and promotion is on, then the default monitor is double-PAL, and the same applies. Again, we expect to set DIPF_IS_PAL for modes of the double-PAL monitor. * Incorrect assumptions about ColorMaps & ColorTables: Because the color system undergoes significant changes, ColorMaps should always be allocated using GetColorMap(); freed using FreeColorMap(); colors changed using LoadRGB4(), SetRGB4(), or SetRGB4CM(); and colors queried using GetRGB4(). Specifically, the value ColorMap->ColorTable and the structure pointed to by it should never be poked or read directly. Unfortunately, the old IFF sample code does NOT call the proper system functions, and instead reads ColorMap->ColorTable directly - This is incorrect, and code based on the original IFF sample code should be checked and changed. The new IFF code (NewIFF.lzh, latest version available in BIX amiga.cert/com/dev listings, sent to ADSP, sent to Fred Fish) has been updated to never access the ColorMap->ColorTable directly. New V39 functions for getting, setting, and loading color registers are provided. These new functions treat color guns (R, G, B) each as 32-bit values for handling both 8-bit guns and any conceivable future needs. Use these new 32-bit color functions when running under at least V39 for future compatibility. When using 4 or 8-bit R/G/B values, scale your values to 32 bits by duplicating your 8 bit value in all 4 bytes of the 32 bit value. When scaling up a 4 bit value, duplicate it in all nibbles. e.g.: 8-bit red value $1F becomes $1F1F1F1F; 4-bit red value $3 becomes $33333333; Important note about NUMBER OF COLORS: Older IFF code (even earlier newiff code) would not load more than 32 color registers. The new code has been updated to base its upper limit for color loading on the ColorMap->Count of the ViewPort of the destination display. Remove old limitations of 32 registers in your code, and replace by limiting to ColorMap->Count registers. The release 2.0 graphics.library VideoControl() function should be used to get, set, or clear the special features associated with ColorMaps. * Poking Copper lists and/or Copinit: The structure and order of Copper lists will change for all modes, so any program that relies on poking the Copper lists will likely break. Certain programs (especially games) make assumptions about copinit and poke it directly -- These programs will break with the new chips. * Dangerous Bits in display hardware: Beware of poking the following bits - In BPLCON0: bits 0, 4, 5, 6, and 7 In BPLCON2: bits 7, 8, 9 In BPLCON3: bits 0,1,6,7, and bits 9 through 15 * Illegal use of the processor to write to BitPlane and Sprite data registers BitPlane and Sprite data registers should NOT be written to by the processor. The correct way for data to be fed to the chips is by setting up DMA that points to the data in CHIP memory. * Illegal re-use of sprites on the same line Attempting to re-use sprites on the same horizontal line by redefining the sprite data is illegal and unsupported. Sprites may only be re-used vertically -- and then only with at least a one line gap between re-uses. See the "Amiga Hardware Reference Manual" for an example of sprite re-use. * Incorrect allocation of sprite Image Data: Because of the increased fetch bandwidth of the new chips, sprite image data must be properly aligned in CHIP memory. Under 2.0, the best way to allocate this memory is to call the exec.library AllocMem() function. * Forgotten FreeSprite(): Sprites may now have a number of different modes. However, under Intuition, these modes are global to all sprites. If a program gets a sprite in a particular mode, but then does not free it, Intuition (and all intuition based programs, including workbench) are forced to use sprites in the mode of the forgotten sprite. In general, it is good practice to not use sprites other than the pointer when coding software that is meant to be Intuition compatible. Taking Advantage of New Features Obviously, new versions of the system software will take advantage of these new chips. But even without new system software, here are some strategies which should allow code to "automagically" take advantage of some of the new software's features. Previously impossible deeper modes: Properly written software can use the calling syntax of the current graphics.library and intuition.library functions to open the ECS screen modes with larger numbers of bitplanes. These modes are simply deeper bitplane versions of existing modes -- lores 6,7, and 8 bits; hires 5,6,7, and 8 bits; super-hires 3,4,5,6,7, and 8 bits; and VGA 3,4,5,6,7, and 8 bits. Obviously, the Display Database must be checked to see if these modes support the desired number of bitplanes before actually trying to use them. Intuition's screen functions should be used to open these previously impossible screens, but programs cannot rely on Intuition to throw out all "bad" possibilities. For example, V36 Intuition will open an 8 bit lores screen, and the 3 high bits simply go unused. Programs will therefore need to explicitly check the display database to find out what the chips support. 39.82 NOTE: Note that starting with this release, Intuition will fail to open a screen which is "too deep". There is a new SA_ErrorCode value, OSERR_TOODEEP. NOTE: The currently defined Display Database ModeIDs have all been moved to the new include file: graphics/modeid.h and .i Do NOT use homebrew modeid's created by OR'ing together monitors and modes. Use only defined modes or modes listed as available in the display database (see AmigaMail, Devcon code, 2.0 RKM Libraries manual, following example, and new screen mode requester example). Given enough chip RAM, this complete example (release 2.0 or greater) will check the display database entry for a LORES screen and open a screen with the maximum allowable number of bitplanes. On an Amiga with any chipset up to and including ECS, this code will open a 5 bitplane screen. On a machine with the next generation chipset, the screen will be 8 bits deep. The code will then draw one vertical line for each available color, using Intuition's "preferred" palette (which is presumably set by the user using preferences.) /* * maxdepthlores.c */ #include #include #include #include #include #include #include #include #include struct IntuitionBase *IntuitionBase; struct GfxBase *GfxBase; extern struct ExecBase *SysBase; void Quit(char whytext[],UBYTE failcode) { if (IntuitionBase) CloseLibrary((struct Library *) IntuitionBase); if (GfxBase) CloseLibrary((struct Library *) GfxBase); printf("%s\n",whytext); Delay(50*10); exit(failcode); } void main(void) { ULONG modeID = LORES_KEY; DisplayInfoHandle displayhandle; struct DimensionInfo dimensioninfo; UWORD maxdepth, maxcolors; ULONG soerror = NULL,colornum; struct Screen *screen; if ((GfxBase= (struct GfxBase *) OpenLibrary("graphics.library",36))==NULL) Quit("graphics.library is too old RastPort),colornum); Move(&(screen->RastPort),colornum,screen->BarHeight + 2); Draw(&(screen->RastPort),colornum,199); } Delay(50*1*6); CloseScreen(screen); } else { /* * Hmmm. Couldn't open the screen. maybe not * enough CHIP RAM? Maybe not enough chips! ;-) */ switch(soerror) { case OSERR_NOCHIPS: Quit("Bummer! You need new chips dude!",25); break; case OSERR_UNKNOWNMODE: Quit("Bummer! Unknown screen mode.",25); break; case OSERR_NOCHIPMEM: Quit("Not enough CHIP memory.",25); break; case OSERR_NOMEM: Quit("Not enough FAST memory.",25); break; default: printf("soerror=%d\n",soerror); Quit("Screen opening error.",25); break; } Quit("Couldn't open screen.",25); } } Opening on Workbench: One of the easiest ways to help a given program peacefully coexist with new hardware is to allow it to open on the Workbench screen (or on any public screen). Software written in such a way that it can operate on any of 2.0's myriad possible Workbench screens should be robust enough that it can find out from the system any information it might need about the environment, and (if it understands the kind of screen that it's on) use the appropriate graphics.library calls to manipulate it's window. Here's some example code that determines the depth of the default public screen and opens a window on it. If it where a real application, the code now has a good idea of how many colors are available on the screen /* depthawarevisitor.c */ #include #include #include #include #include #include #include #include #include struct IntuitionBase *IntuitionBase; struct GfxBase *GfxBase; extern struct ExecBase *SysBase; void Quit(char whytext[],UBYTE failcode) { if (IntuitionBase) CloseLibrary((struct Library *) IntuitionBase); if (GfxBase) CloseLibrary((struct Library *) GfxBase); printf("%s\n",whytext); Delay(50*10); exit(failcode); } void main(void) { struct Screen *screen; struct DrawInfo *drawinfo; struct Window *window; UWORD depth; if ((GfxBase= (struct GfxBase *) OpenLibrary("graphics.library",36))==NULL) Quit("graphics.library is too old dri_Depth; /* Because Intuition allocates the DrawInfo structure, * we have to tell it when we're done, to get the memory back. */ FreeScreenDrawInfo(screen, drawinfo); /* This next line takes advantage of the stack-based amiga.lib * version of OpenWindowTags. */ if (window = OpenWindowTags(NULL, WA_PubScreen ,screen, WA_Left ,0, WA_Width ,screen->Width, WA_Top ,screen->BarHeight, WA_Height, screen->Height - screen->BarHeight, WA_Flags, WINDOWDRAG|WINDOWDEPTH|WINDOWCLOSE|ACTIVATE|SIMPLE_REFRESH|NOCAREREFRESH, WA_Title ,"Big Visitor", TAG_END)) { /* because we're a visitor, we can unlock the screen as soon * as the window is open */ UnlockPubScreen(NULL,screen); printf("depth=%d\n",depth); /* All our window event handling might go here */ Delay(50*10); /* Of course, some other program might come along * and change the attributes of the screen that we read from * DrawInfo, but that's a mean thing to do to a public screen, * so let's hope it doesn't happen. */ CloseWindow(window); } else UnlockPubScreen(NULL,screen); /* OpenWindow failed, but we still have * to let go of the screen. */ } Direct Hardware Access: So many of the internal mechanisms (especially those dealing with color) are changing, that developers who insist on directly hitting the hardware have no real way of writing software today which will even run with, let alone take advantage of, tomorrow's chips. What to Expect From New OS Software Graphics.library: Graphics.library enhanced to handle the capabilities offered by the new chips. Allocation Issues - New functions to properly initialize and allocate structures (like BitMaps and planes) which can take advantage of the chips' new modes. Color Palette Handling - The new chips will handle color in new and different ways. A number of new software features deal with this new color scheme. "RGB" functions - New versions of the "RGB" functions (Set, Load, Get, etc.) which will handle the structure of the new Color Table. Palette sharing - Shared or exclusive access to colors in the current colormap. Display Database - The functionality of the Display Database increased to provide applications with even more detailed information about available modes. Get and Set Functions - Because of the number of changes and extensions to system structures related to graphics, new functions will allow the safe manipulation of these structures. Sprite Handling - New methods of allocating and generating acceptable sprite image data will be provided. Intuition.library: Intuition enhanced to take advantage of the new graphics abilities. Table 1: New Modes (In Addition to Modes Supported by ECS) Mode Planes Colors Bandwidth (See note 1) ---- ------ ------ ---------------------- LORES (320x200) 6 64 1 7 128 1 8 256 1 8 HAM 256,000+ (see note 2) 1 HIRES (640x200) 5 32 2 6 EHB 64 (see note 3) 2 6 HAM 4096 (see note 4) 2 6 64 2 7 128 2 8 256 2 8 HAM 256,000+ (see note 2) 2 SUPERHIRES (1280x200) 1 2 (see note 5) 1 2 4 (see note 5) 1 3 8 2 4 16 2 5 32 4 6 EHB 64 (see note 3) 4 6 HAM 4096 (see note 4) 4 6 64 4 7 128 4 8 256 4 8 HAM 256,000+ (see note 2) 4 VGA (160,320,640x480 non-int.) 1 2 (see note 5) 1 2 4 (see note 5) 1 3 8 2 4 16 2 5 32 4 6 EHB 64 (see note 3) 4 6 HAM 4096 (see note 4) 4 6 64 4 7 128 4 8 256 4 8 HAM 256,000+ (see note 2) 4 Notes: 1 - The "Bandwidth" number describes the amount of fetch bandwidth required by a particular screen mode. For example, a 5 bit deep VGA screen requires the 4x bandwidth fetch mode while a 1 bit VGA screen requires only the 1x mode.. This translates to the hardware having to move data 4 times faster. To be able to move data at these higher rates, the higher bandwidth modes require data to be properly aligned in CHIP memory that is fast enough to support the bandwidth. Specifically, bandwidth fetch mode factors of 1 require data to be on 16 bit boundaries, factors of 2 require 32 bit boundaries, and factors of 4 require 64 bit boundaries. Restrictions like these are the best reason to use the system allocation functions whenever data is being prepared for the custom hardware. It is not guaranteed that all machines that have the new chipset will also have memory fast enough for the 4x modes. Therefore, the ONLY way to know whether or not the machine will support the mode you want is to check the Display Database. 2 - New 8 bit HAM mode uses the upper 6 bits for 64 24-bit base register colors or as a 6 bit modify value, plus the lower 2 bits for 18 bit hold or modify mode control. This mode could conceivably allow simultaneous display of more than 256,000 colors (up to 16.8 million, presuming a monitor / screenmode with enough pixels.) Please note that while the register planes and control planes are internally reversed in 8 bit HAM (the control bits are the two LSBs instead of the two MSBs), programs using graphics.library and intuition.library will not have to deal with this reversal, as it will be handled automatically for them. 3 - This is like the original EHB mode, but in new resolutions. It uses 5 bits to yield 32 register colors, plus a sixth bit for 32 colors that are 1/2 as bright. 4 - This is like the original 6 bit Ham mode, but in new resolutions. It uses the lower 4 bits for 16 register colors, plus the upper 2 bits for modify mode control. This mode allows simultaneous display of 4096 colors. 5 - These modes are unlike the old VGA and SUPERHIRES modes in that they are not restricted to a nonstandard 64 color palette.  (( <./\.| )) The 7th <hurch of the /\pocalyptic |awnmower! (( <./\.| ))  -+*$> ANTHROX UNITED KINGDOM/LONDON HEADQUARTERS: +44-81-459-4243 [AMI] <$*+-  (( <./\.| )) The 7th <hurch of the /\pocalyptic |awnmower! (( <./\.| ))  AACHIP.TXT UPLOADED TO <./\.| BBS By Mr.P0T-NOoDLE At WHENEVER +-------------------------------------------------------------------------+ | THIS FILE HAS BEEN UPLOADED TO | | *-== UNKNOWN PLEASURES ==-* | | ALLIANCE WORLD HEADQUARTERS = 0204 29917 | | 16.8 USR Dual Standard / Latest Warez FAST! | +-------------------------------------------------------------------------+